ctlimits
ctlimits is a utility for establishing and managing usage limits on cryptographic keys within the ProtectToolkit-C environment.
The utility will recognize older firmware and report meaningful error messages.
Syntax
The following ctlimits syntax can be used.
Create ticket from offline specification
ctlimits ct -k<keyspec> -S<serial_no> -i<key_id> -t<tok_label> -l<target_label> [-U<usertype>] [-m<message>] [-d<days>] [-L<limit>] [-s<date>] [-e<date>] [-c<cert_filename>] <filename>
Present ticket to HSM
ctlimits pt <filename> [-U<usertype>] [-O<objtype>] -k<keyspec> [-i<key_id>]
Apply limit attributes directly
ctlimits up -k<keyspec> [-U<usertype>] [-O<objtype>] [-i<key_id>] [-C<count>] [-L<limit>] [-s<date>] [-e<date>] [-c<cert_filename>]
View key attributes
ctlimits vk -k<keyspec> [-U<usertype>] [-O<objtype>] [-i<key_id>]
Commands
The following ctlimits commands are available.
- ct
-
This command creates a SET ATTRIBUTES ticket in the file filename.
This ticket can be presented to a ProtectToolkit-C HSM using the ctlimitspt command. The ticket is signed with the authority of the user type specified by -U option (or the CKU_USER if no -U option is provided).
-
The key specified by -k parameter is used to identify the signing key used to sign the ticket.
-
The -k parameter can be used to optionally provide the utility with a pin value. If none is supplied the utility will prompt the operator to enter one.
-
If the -m option is specified then a message, which can be used to identify the ticket, is included into the file containing the ticket.
-
To identify the target object completely all the -l, -t, -S and -i options must be specified
-
At least one of the -c, -L, -s and -e options must be provided In order to indicate the change required.
-
The valid time for the ticket is one day unless the -d option is used to specify a different duration.
-
- pt
-
This command reads a SET ATTRIBUTES ticket from filename and attempts to find the key in the token indicated by the -l, -t, and optionally the -i options.
If the key object is not found inside the token then the utility will attempt to login as the USER and will search again. In this case the USER pin is required. The -u option can be used to supply the USER pin or if this is not provided then the utility will prompt the operator to enter the USER pin.
- up
-
This command sets or updates attributes on the target object directly without making an intermediate ticket file. The object must be modifiable.
To identify the target object the -l and -t options must be provided. To further identify the target object the -i option can be specified.
The target object will have its attributes updated according to the -C, -L, -s, -e and -c options. At least one of these options must be provided.
After the command sets the new attributes it will lock the object by setting the CKA_MODIFIABLE to False (in a C_CopyObject operation).
If the key object is not found inside the token then the utility will attempt to login as the USER and will search again. In this case the USER pin is required. The -k option can be used to supply the USER pin or if this is not provided then the utility will prompt the operator to enter the USER pin.
- vk
-
This command displays the current limits attributes of an object.
To identify the target object the -k option must be provided. To further identify the target object the -i option can be specified.
If the key object is not found inside the token then the utility will attempt to login as the USER and will search again. In this case the USER pin is required. The -k option can be used to supply the USER pin or if this is not provided then the utility will prompt the operator to enter the USER pin.
Options
The following ctlimits options are available.
- -U<user>, --usertype=<user>
-
User type creating ticket - can be either SO or USER (default)
- -k<keyspec>, --keyspec=<keyspec>
-
Specification of a key. The format used is TokenLabel(pin)/KeyLabel,
where the pin is optional and TokenLabel can specify slot by number
For example:
-k MyToken(1234)/MyKey (Pin 1234) or
-k MyToken/MyKey (no Pin - utility may prompt for pin)
-k SLOTID=2/MyKey
- -O<objtype>, --objtype=<objtype>
-
Object type of the key. can be secret_key, certificate, public_key, or private_key. The default is private_key.
- -m<message>, --message=<message>
-
Optional message to add to ticket
- -t<tok_label>, --token_label=<tok_label>
-
Label of token containing the target object (can be numeric to refer to token by slot number)
- -S<serial_no>, --tok_sno=<serial_no>
-
Serial number of Token containing the target object.
- -l<target_label>, --target_label=<target_label>
-
Label of object that is the target of the operation
- -i<key_id>, --target_key_id=<key_id>
-
Key ID of object that is the target of the operation.
key_id **should be in HEX format.
- -C<count>, --usage_count=<count>
-
Specify CKA_USAGE_COUNT value, ‘count’ is in decimal format.
- -L<limit>, --usage_limit=<limit>
-
Specify CKA_USAGE_LIMIT value, ‘limit’ is in decimal format.
- -s<date>, --start_date=<date>
-
Specify new CKA_START_DATE value for the target object.
‘time’ format is YYYYMMDD - time is GMT.
- -e<date>, --end_date=<date>
-
Specify new CKA_END_DATE value for the target object.
‘time’ format is YYYYMMDD - the time specified is GMT.
- -c<cert_filename>, --cert=<cert_filename>
-
Name of the file containing a public key certificate to be applied to CKA_ADMIN_CERT attribute
- -d<days>, --duration=<days>
-
Validity period of ticket in days
